Inside Macintosh: QuickTime Components
Some video digitizer components may provide functions that allow applications to work with digitizing devices that can provide compressed image data directly. Such devices allow applications to retrieve compressed image data without using the Image Compression Manager. However, in order to display images from the compressed data stream, there must be an appropriate decompressor component available to decompress the image data.
Video digitizers that can support compressed source devices set the digiOutDoesCompress flag to 1 in their capability flags (see "Capability Flags," for more information about these flags).
Applications can use the VDGetCompressionTypes function to determine the image-compression capabilities of a video digitizer. The VDSetCompression function allows applications to set some parameters that govern image compression.
Applications control digitization by calling the VDCompressOneFrameAsync function, which instructs the video digitizer to create one frame of compressed image data. The VDCompressDone function returns that frame. When an application is done with a frame, it calls the VDReleaseCompressBuffer function to free the buffer. An application can force the digitizer to place a key frame into the sequence by calling the VDResetCompressSequence function. Applications can turn compression on and off by calling VDSetCompressionOnOff .
Applications can obtain the digitizer's image description structure by calling the VDGetImageDescription function. Applications can set the digitizer's time base by calling the VDSetTimeBase function.
All of the digitizing functions described in this section support only asynchronous digitization. That is, the video digitizer works independently to digitize each frame. Applications are free to perform other work while the digitizer works on each frame.
The video digitizer component manages its own buffer pool for use with these functions. In this respect, these functions differ from the other video digitizer functions that support asynchronous digitization (see "Controlling Digitization," for more information about these functions).
The VDGetCompressionTypes function allows an application to determine the image-compression capabilities of the video digitizer.
pascal VideoDigitizerError VDGetCompressionTypes
(VideoDigitizerComponent ci,
VDCompressionListHandle h);
The video digitizer places its preferred, or default, compression options in the first compression list structure in the returned array.
Note that there must be a decompressor component of the appropriate type available in the system if an application is to display images from a compressed image sequence.
The VDCompressionList data type defines the format and content of the compression list structure:
typedef struct VDCompressionList {
CodecComponent codec; /* component ID */
CodecType cType; /* compressor type */
Str63 typeName; /* compression algorithm */
Str63 name; /* compressor name string */
long formatFlags; /* data format flags */
long compressFlags; /* capabilities flags */
long reserved; /* set to 0 */
} VDCompressionList, *VDCompressionListPtr, **VDCompressionListHandle;
The VDSetCompression function allows applications to specify some compression parameters.
pascal VideoDigitizerError VDSetCompression
(VideoDigitizerComponent ci,
OSType compressType, short depth,
Rect *bounds, CodecQ spatialQuality,
CodecQ temporalQuality,
long keyFrameRate);
An application may use the VDSetCompression function to control the parameters that govern image compression. An application may change the compressor type, image depth, and boundary rectangle parameters only when the digitizer is stopped. However, if an application sets these three parameters (that is, the compressType , depth , and bounds parameters) to 0, it may work with the other parameters while digitization is active. This allows an application to vary the data rate during digitization.
The VDSetCompressionOnOff function allows an application to start and stop compression by digitizers that can deliver either compressed or uncompressed image data.
pascal VideoDigitizerError VDSetCompressionOnOff
(VideoDigitizerComponent ci,
Boolean state);
This is a required function for digitizers that are going to perform compression. These digitizers have their digiOutDoesCompress capability flag set to 1 and their digiOutDoesCompressOnly flag set to 0. Digitizers that support this capability typically deliver uncompressed image data in addition to the compressed data stream; the uncompressed data is ready for display.
Digitizers that only provide compressed data have their digiOutDoesCompressOnly flag set to 1, rather than 0. These digitizers may either ignore this function or return a nonzero result code.
Applications must call this function before they call either VDSetCompression or VDCompressOneFrameAsync . This allows the video digitizer to prepare for the operation.
The VDCompressOneFrameAsync function instructs the video digitizer to digitize and compress a single frame of image data. Because the component performs this action asynchronously, the application is free to do other things while the digitizer works on the image.
pascal VideoDigitizerError VDCompressOneFrameAsync
(VideoDigitizerComponent ci);
An application can determine when the digitizer is done with the frame by calling the VDCompressDone function, which is discussed next.
Unlike the VDGrabOneFrameAsync function (discussed on VDGrabOneFrameAsync ), the video digitizer handles all details of managing data buffers.
The VDCompressDone function allows an application to determine whether the video digitizer has finished digitizing and compressing a frame of image data. An application starts the digitizing process by calling the VDCompressOneFrameAsync function, which was just discussed.
pascal VideoDigitizerError VDCompressDone
(VideoDigitizerComponent ci,
Boolean *done, Ptr *theData,
long *dataSize,
UInt8 *similarity,
TimeRecord *t);
An application can determine when the digitizer is done with the frame by calling the VDCompressDone function. When the digitizer is done, it sets the Boolean value referred to by the done parameter to true , and then returns information about the digitized and compressed frames via the theData , dataSize , similarity , and t parameters.
If the digitizer is not yet done, it sets the Boolean value to false . In this case, the digitizer does not return any other information.
Note that the digitizer is careful to return the frames in temporal order, and to avoid returning two frames with the same time value (unless the rate is set to 0).
The VDReleaseCompressBuffer function allows an application to free a buffer received from the VDCompressDone function.
pascal VideoDigitizerError VDReleaseCompressBuffer
(VideoDigitizerComponent ci,
Ptr bufferAddr);
The VDGetImageDescription function allows an application to retrieve an image description structure from a video digitizer.
pascal VideoDigitizerError VDGetImageDescription
(VideoDigitizerComponent ci,
ImageDescriptionHandle desc);
The VDResetCompressSequence function allows an application to force the video digitizer to insert a key frame into a temporally compressed image sequence.
pascal VideoDigitizerError VDResetCompressSequence
(VideoDigitizerComponent ci);
After an application calls this function, the digitizer ensures that the next frame returned to the application is a key frame.
An application can control the rate at which the digitizer inserts key frames by calling the VDSetCompression function, which is discussed beginning on VDSetCompression .
The VDSetTimeBase function allows an application to establish the video digitizer's time coordinate system.
pascal VideoDigitizerError VDSetTimeBase
(VideoDigitizerComponent ci,
TimeBase t);
Video digitizers return all time information in relation to the specified time base. For example, whenever a digitizer returns a compressed frame from its VDCompressDone function, it returns time information relating to the time when the frame was digitized and compressed. This time information is expressed in the time base that the application specifies with this function.